## 最简单：直接用模板项目（推荐）

立即上手而不纠结配置细节，点击下面链接即可：

<div className="not-prose mt-2">
  <a
    className="docs-cta-primary"
    href="https://github.com/icebreaker-template/uni-app-x-hbuilderx"
    target="_blank"
    rel="noopener noreferrer"
  >
    <i className="icon-[mdi--rocket-launch] text-lg" />
    使用模板一键开始
  </a>
</div>

打开后按 README 步骤，用 HBuilderX 运行到 Android 模拟器或真机即可看到效果。

---

## 手动集成（由浅入深）

你也可以按下面步骤，从零开始完成配置。

### 前置条件

- 已安装最新 HBuilderX
- 安装 Node.js（建议 ≥ 18）
- 建议准备 Android 模拟器（或真机），便于快速验证

### 1) 创建项目

在 HBuilderX 中创建一个全新的 `uni-app x` 项目；随后在项目根目录初始化 `package.json`：

```bash npm2yarn
npm init -y
```

> 也可以手动创建 `package.json` 文件。

### 2) 安装并引入 Tailwind CSS 3

```bash npm2yarn
# 安装 tailwindcss@3 所需依赖
npm i -D tailwindcss@3 postcss autoprefixer
```

```bash npm2yarn
# 初始化 Tailwind 配置文件
npx tailwindcss init
```

在应用入口 `App.uvue` 中全局引入：

```html title="App.uvue"
<style>
@tailwind base;
@tailwind components;
@tailwind utilities;
</style>
```

### 3) 安装 weapp-tailwindcss 并添加补丁脚本

```bash npm2yarn
npm i -D weapp-tailwindcss
```

在 `package.json` 中增加 `postinstall` 脚本：

```json title="package.json"
{
  "scripts": {
    // highlight-next-line
    "postinstall": "weapp-tw patch"
  }
}
```

> 了解原因可阅读：<a href="/docs/quick-start/this-plugin">weapp-tailwindcss 使用说明</a>

### 4) 在 uni-app x 中注册 weapp-tailwindcss

先创建一个简单的路径工具函数，方便在配置里引用绝对路径：

```js title="shared.js"
const path = require('node:path')
function r(...args) {
  return path.resolve(__dirname, ...args)
}
module.exports = { r }
```

创建 `vite.config.ts` 并注册插件（注意 `uniAppX` 预设来自 `weapp-tailwindcss/presets`）：

```js title="vite.config.ts"
import { defineConfig } from 'vite'
import uni from '@dcloudio/vite-plugin-uni'
import { UnifiedViteWeappTailwindcssPlugin } from 'weapp-tailwindcss/vite'
import { r } from './shared'
import { uniAppX } from 'weapp-tailwindcss/presets'
import tailwindcss from 'tailwindcss'

export default defineConfig({
  plugins: [
    uni(),
    UnifiedViteWeappTailwindcssPlugin(
      uniAppX({
        base: __dirname,
        rem2rpx: true,
      }),
    ),
  ],
  css: {
    postcss: {
      plugins: [
        tailwindcss({
          config: r('./tailwind.config.js'),
        }),
      ],
    },
  },
})
```

### 5) 配置 Tailwind

使用绝对路径包含所有需要提取原子类的文件：

```js title="tailwind.config.js"
const { r } = require('./shared')

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    r('./pages/**/*.{uts,uvue}'),
    r('./components/**/*.{uts,uvue}'),
  ],
  corePlugins: {
    // 由 uni-app x 提供基础样式，这里关闭 preflight 避免冲突
    preflight: false,
  },
}
```

如需从更多目录提取样式，按需扩展 `content` 的 glob。

### 6) 运行与验证

import run from './assets/run.png'

- 在 HBuilderX 中点击「运行」并选择目标平台（推荐 Android 模拟器/真机）  
- 新建/打开任意页面，写入示例类名验证：

```html
<view class="p-4">
  <text class="text-xl text-red-500 font-medium">Hello Tailwind on uni-app x</text>
</view>
```

<img className="h-60" src={run} alt="运行" />

### 7) 编辑器智能提示（可选）

VS Code 配合插件体验最佳。为 Tailwind 扩展增加语言映射，让其识别 `uvue/uts`：

```json title=".vscode/settings.json"
{
  "tailwindCSS.includeLanguages": {
    "uvue": "html",
    "uts": "javascript"
  }
}
```

同时安装官方语言服务插件（ID: dcloud-ide.hbuilderx-language-services）以获得完整语法支持。

---

## 重要说明与限制

- 仅推荐在 `tailwindcss@3.x` 下跨端使用（v4 在该场景下暂不兼容）
- 原生 App 端对文本与部分 CSS 特性有约束：文本使用 `<text>` 元素，且样式需直接作用其上
- 如遇到 HBuilderX 控制台 CSS 警告，请按提示做兼容性调整或采用条件编译
